/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.configuration;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.Reader;
import java.io.Writer;
import java.net.URL;
import java.net.URLConnection;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.transform.OutputKeys;
import javax.xml.transform.Result;
import javax.xml.transform.Source;
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerException;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.TransformerFactoryConfigurationError;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.stream.StreamResult;
import org.apache.commons.configuration.tree.ConfigurationNode;
import org.w3c.dom.Attr;
import org.w3c.dom.CDATASection;
import org.w3c.dom.DOMException;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.NamedNodeMap;
import org.w3c.dom.NodeList;
import org.w3c.dom.Text;
import org.xml.sax.EntityResolver;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;
import org.xml.sax.helpers.DefaultHandler;
/**
* <p>A specialized hierarchical configuration class that is able to parse XML
* documents.</p>
*
* <p>The parsed document will be stored keeping its structure. The class also
* tries to preserve as much information from the loaded XML document as
* possible, including comments and processing instructions. These will be
* contained in documents created by the <code>save()</code> methods, too.</p>
*
* <p>Like other file based configuration classes this class maintains the name
* and path to the loaded configuration file. These properties can be altered
* using several setter methods, but they are not modified by <code>save()</code>
* and <code>load()</code> methods. If XML documents contain relative paths to
* other documents (e.g. to a DTD), these references are resolved based on the
* path set for this configuration.</p>
*
* <p>By inheriting from <code>{@link AbstractConfiguration}</code> this class
* provides some extended functionality, e.g. interpolation of property values.
* Like in <code>{@link PropertiesConfiguration}</code> property values can
* contain delimiter characters (the comma ',' per default) and are then split
* into multiple values. This works for XML attributes and text content of
* elements as well. The delimiter can be escaped by a backslash. As an example
* consider the following XML fragment:</p>
*
* <p>
* <pre>
* <config>
* <array>10,20,30,40</array>
* <scalar>3\,1415</scalar>
* <cite text="To be or not to be\, this is the question!"/>
* </config>
* </pre>
* </p>
* <p>Here the content of the <code>array</code> element will be split at
* the commas, so the <code>array</code> key will be assigned 4 values. In the
* <code>scalar</code> property and the <code>text</code> attribute of the
* <code>cite</code> element the comma is escaped, so that no splitting is
* performed.</p>
*
* <p>The configuration API allows setting multiple values for a single attribute,
* e.g. something like the following is legal (assuming that the default
* expression engine is used):
* <pre>
* XMLConfiguration config = new XMLConfiguration();
* config.addProperty("test.dir[@name]", "C:\\Temp\\");
* config.addProperty("test.dir[@name]", "D:\\Data\\");
* </pre></p>
*
* <p>Because in XML such a constellation is not directly supported (an attribute
* can appear only once for a single element), the values are concatenated to a
* single value. If delimiter parsing is enabled (refer to the
* <code>{@link #setDelimiterParsingDisabled(boolean)}</code> method), the
* current list delimiter character will be used as separator. Otherwise the
* pipe symbol ("|") will be used for this purpose. No matter which character is
* used as delimiter, it can always be escaped with a backslash. A backslash
* itself can also be escaped with another backslash. Consider the following
* example fragment from a configuration file:
* <pre>
* <directories names="C:\Temp\\|D:\Data\"/>
* </pre>
* Here the backslash after Temp is escaped. This is necessary because it
* would escape the list delimiter (the pipe symbol assuming that list delimiter
* parsing is disabled) otherwise. So this attribute would have two values.</p>
*
* <p>Note: You should ensure that the <em>delimiter parsing disabled</em>
* property is always consistent when you load and save a configuration file.
* Otherwise the values of properties can become corrupted.</p>
*
* <p>Whitespace in the content of XML documents is trimmed per default. In most
* cases this is desired. However, sometimes whitespace is indeed important and
* should be treated as part of the value of a property as in the following
* example:
* <pre>
* <indent> </indent>
* </pre></p>
*
* <p>Per default the spaces in the <code>indent</code> element will be trimmed
* resulting in an empty element. To tell <code>XMLConfiguration</code> that
* spaces are relevant the <code>xml:space</code> attribute can be used, which is
* defined in the <a href="http://www.w3.org/TR/REC-xml/#sec-white-space">XML
* specification</a>. This will look as follows:
* <pre>
* <indent <strong>xml:space="preserve"</strong>> </indent>
* </pre>
* The value of the <code>indent</code> property will now contain the spaces.</p>
*
* <p><code>XMLConfiguration</code> implements the <code>{@link FileConfiguration}</code>
* interface and thus provides full support for loading XML documents from
* different sources like files, URLs, or streams. A full description of these
* features can be found in the documentation of
* <code>{@link AbstractFileConfiguration}</code>.</p>
*
* <p><em>Note:</em>Configuration objects of this type can be read concurrently
* by multiple threads. However if one of these threads modifies the object,
* synchronization has to be performed manually.</p>
*
* @since commons-configuration 1.0
*
* @author Jörg Schaible
* @author Oliver Heger
* @version $Revision: 721895 $, $Date: 2008-11-30 22:08:42 +0100 (So, 30 Nov 2008) $
*/
public class XMLConfiguration extends AbstractHierarchicalFileConfiguration
implements EntityResolver
{
/**
* The serial version UID.
*/
private static final long serialVersionUID = 2453781111653383552L;
/** Constant for the default root element name. */
private static final String DEFAULT_ROOT_NAME = "configuration";
/** Constant for the name of the space attribute.*/
private static final String ATTR_SPACE = "xml:space";
/** Constant for the xml:space value for preserving whitespace.*/
private static final String VALUE_PRESERVE = "preserve";
/** Constant for the delimiter for multiple attribute values.*/
private static final char ATTR_VALUE_DELIMITER = '|';
/** The document from this configuration's data source. */
private Document document;
/** Stores a map with the registered public IDs.*/
private Map registeredEntities = new HashMap();
/** Stores the name of the root element. */
private String rootElementName;
/** Stores the public ID from the DOCTYPE.*/
private String publicID;
/** Stores the system ID from the DOCTYPE.*/
private String systemID;
/** Stores the document builder that should be used for loading.*/
private DocumentBuilder documentBuilder;
/** Stores a flag whether DTD validation should be performed.*/
private boolean validating;
/** A flag whether attribute splitting is disabled.*/
private boolean attributeSplittingDisabled;
/**
* Creates a new instance of <code>XMLConfiguration</code>.
*/
public XMLConfiguration()
{
super();
}
/**
* Creates a new instance of <code>XMLConfiguration</code> and copies the
* content of the passed in configuration into this object. Note that only
* the data of the passed in configuration will be copied. If, for instance,
* the other configuration is a <code>XMLConfiguration</code>, too,
* things like comments or processing instructions will be lost.
*
* @param c the configuration to copy
* @since 1.4
*/
public XMLConfiguration(HierarchicalConfiguration c)
{
super(c);
clearReferences(getRootNode());
setRootElementName(getRootNode().getName());
}
/**
* Creates a new instance of <code>XMLConfiguration</code>. The
* configuration is loaded from the specified file
*
* @param fileName the name of the file to load
* @throws ConfigurationException if the file cannot be loaded
*/
public XMLConfiguration(String fileName) throws ConfigurationException
{
super(fileName);
}
/**
* Creates a new instance of <code>XMLConfiguration</code>.
* The configuration is loaded from the specified file.
*
* @param file the file
* @throws ConfigurationException if an error occurs while loading the file
*/
public XMLConfiguration(File file) throws ConfigurationException
{
super(file);
}
/**
* Creates a new instance of <code>XMLConfiguration</code>.
* The configuration is loaded from the specified URL.
*
* @param url the URL
* @throws ConfigurationException if loading causes an error
*/
public XMLConfiguration(URL url) throws ConfigurationException
{
super(url);
}
/**
* Returns the name of the root element. If this configuration was loaded
* from a XML document, the name of this document's root element is
* returned. Otherwise it is possible to set a name for the root element
* that will be used when this configuration is stored.
*
* @return the name of the root element
*/
public String getRootElementName()
{
if (getDocument() == null)
{
return (rootElementName == null) ? DEFAULT_ROOT_NAME : rootElementName;
}
else
{
return getDocument().getDocumentElement().getNodeName();
}
}
/**
* Sets the name of the root element. This name is used when this
* configuration object is stored in an XML file. Note that setting the name
* of the root element works only if this configuration has been newly
* created. If the configuration was loaded from an XML file, the name
* cannot be changed and an <code>UnsupportedOperationException</code>
* exception is thrown. Whether this configuration has been loaded from an
* XML document or not can be found out using the <code>getDocument()</code>
* method.
*
* @param name the name of the root element
*/
public void setRootElementName(String name)
{
if (getDocument() != null)
{
throw new UnsupportedOperationException("The name of the root element "
+ "cannot be changed when loaded from an XML document!");
}
rootElementName = name;
getRootNode().setName(name);
}
/**
* Returns the <code>DocumentBuilder</code> object that is used for
* loading documents. If no specific builder has been set, this method
* returns <b>null</b>.
*
* @return the <code>DocumentBuilder</code> for loading new documents
* @since 1.2
*/
public DocumentBuilder getDocumentBuilder()
{
return documentBuilder;
}
/**
* Sets the <code>DocumentBuilder</code> object to be used for loading
* documents. This method makes it possible to specify the exact document
* builder. So an application can create a builder, configure it for its
* special needs, and then pass it to this method.
*
* @param documentBuilder the document builder to be used; if undefined, a
* default builder will be used
* @since 1.2
*/
public void setDocumentBuilder(DocumentBuilder documentBuilder)
{
this.documentBuilder = documentBuilder;
}
/**
* Returns the public ID of the DOCTYPE declaration from the loaded XML
* document. This is <b>null</b> if no document has been loaded yet or if
* the document does not contain a DOCTYPE declaration with a public ID.
*
* @return the public ID
* @since 1.3
*/
public String getPublicID()
{
return publicID;
}
/**
* Sets the public ID of the DOCTYPE declaration. When this configuration is
* saved, a DOCTYPE declaration will be constructed that contains this
* public ID.
*
* @param publicID the public ID
* @since 1.3
*/
public void setPublicID(String publicID)
{
this.publicID = publicID;
}
/**
* Returns the system ID of the DOCTYPE declaration from the loaded XML
* document. This is <b>null</b> if no document has been loaded yet or if
* the document does not contain a DOCTYPE declaration with a system ID.
*
* @return the system ID
* @since 1.3
*/
public String getSystemID()
{
return systemID;
}
/**
* Sets the system ID of the DOCTYPE declaration. When this configuration is
* saved, a DOCTYPE declaration will be constructed that contains this
* system ID.
*
* @param systemID the system ID
* @since 1.3
*/
public void setSystemID(String systemID)
{
this.systemID = systemID;
}
/**
* Returns the value of the validating flag.
*
* @return the validating flag
* @since 1.2
*/
public boolean isValidating()
{
return validating;
}
/**
* Sets the value of the validating flag. This flag determines whether
* DTD validation should be performed when loading XML documents. This
* flag is evaluated only if no custom <code>DocumentBuilder</code> was set.
*
* @param validating the validating flag
* @since 1.2
*/
public void setValidating(boolean validating)
{
this.validating = validating;
}
/**
* Returns the flag whether attribute splitting is disabled.
*
* @return the flag whether attribute splitting is disabled
* @see #setAttributeSplittingDisabled(boolean)
* @since 1.6
*/
public boolean isAttributeSplittingDisabled()
{
return attributeSplittingDisabled;
}
/**
* <p>
* Sets a flag whether attribute splitting is disabled.
* </p>
* <p>
* The Configuration API allows adding multiple values to an attribute. This
* is problematic when storing the configuration because in XML an attribute
* can appear only once with a single value. To solve this problem, per
* default multiple attribute values are concatenated using a special
* separator character and split again when the configuration is loaded. The
* separator character is either the list delimiter character (see
* {@link #setListDelimiter(char)}) or the pipe symbol ("|") if
* list delimiter parsing is disabled.
* </p>
* <p>
* In some constellations the splitting of attribute values can have
* undesired effects, especially if list delimiter parsing is disabled and
* attributes may contain the "|" character. In these cases it is
* possible to disable the attribute splitting mechanism by calling this
* method with a boolean value set to <b>false</b>. If attribute splitting
* is disabled, the values of attributes will not be processed, but stored
* as configuration properties exactly as they are returned by the XML
* parser.
* </p>
* <p>
* Note that in this mode multiple attribute values cannot be handled
* correctly. It is possible to create a <code>XMLConfiguration</code>
* object, add multiple values to an attribute and save it. When the
* configuration is loaded again and attribute splitting is disabled, the
* attribute will only have a single value, which is the concatenation of
* all values set before. So it lies in the responsibility of the
* application to carefully set the values of attributes.
* </p>
* <p>
* As is true for the {@link #setDelimiterParsingDisabled(boolean)} method,
* this method must be called before the configuration is loaded. So it
* can't be used together with one of the constructors expecting the
* specification of the file to load. Instead the default constructor has to
* be used, then <code>setAttributeSplittingDisabled(false)</code> has to be
* called, and finally the configuration can be loaded using one of its
* <code>load()</code> methods.
* </p>
*
* @param attributeSplittingDisabled <b>true</b> for disabling attribute
* splitting, <b>false</b> for enabling it
* @see #setDelimiterParsingDisabled(boolean)
* @since 1.6
*/
public void setAttributeSplittingDisabled(boolean attributeSplittingDisabled)
{
this.attributeSplittingDisabled = attributeSplittingDisabled;
}
/**
* Returns the XML document this configuration was loaded from. The return
* value is <b>null</b> if this configuration was not loaded from a XML
* document.
*
* @return the XML document this configuration was loaded from
*/
public Document getDocument()
{
return document;
}
/**
* Removes all properties from this configuration. If this configuration
* was loaded from a file, the associated DOM document is also cleared.
*/
public void clear()
{
super.clear();
document = null;
}
/**
* Initializes this configuration from an XML document.
*
* @param document the document to be parsed
* @param elemRefs a flag whether references to the XML elements should be set
*/
public void initProperties(Document document, boolean elemRefs)
{
if (document.getDoctype() != null)
{
setPublicID(document.getDoctype().getPublicId());
setSystemID(document.getDoctype().getSystemId());
}
constructHierarchy(getRoot(), document.getDocumentElement(), elemRefs, true);
getRootNode().setName(document.getDocumentElement().getNodeName());
if (elemRefs)
{
getRoot().setReference(document.getDocumentElement());
}
}
/**
* Helper method for building the internal storage hierarchy. The XML
* elements are transformed into node objects.
*
* @param node the actual node
* @param element the actual XML element
* @param elemRefs a flag whether references to the XML elements should be set
* @param trim a flag whether the text content of elements should be trimmed;
* this controls the whitespace handling
*/
private void constructHierarchy(Node node, Element element, boolean elemRefs, boolean trim)
{
boolean trimFlag = shouldTrim(element, trim);
processAttributes(node, element, elemRefs);
StringBuffer buffer = new StringBuffer();
NodeList list = element.getChildNodes();
for (int i = 0; i < list.getLength(); i++)
{
org.w3c.dom.Node w3cNode = list.item(i);
if (w3cNode instanceof Element)
{
Element child = (Element) w3cNode;
Node childNode = new XMLNode(child.getTagName(),
elemRefs ? child : null);
constructHierarchy(childNode, child, elemRefs, trimFlag);
node.addChild(childNode);
handleDelimiters(node, childNode, trimFlag);
}
else if (w3cNode instanceof Text)
{
Text data = (Text) w3cNode;
buffer.append(data.getData());
}
}
String text = buffer.toString();
if (trimFlag)
{
text = text.trim();
}
if (text.length() > 0 || !node.hasChildren())
{
node.setValue(text);
}
}
/**
* Helper method for constructing node objects for the attributes of the
* given XML element.
*
* @param node the actual node
* @param element the actual XML element
* @param elemRefs a flag whether references to the XML elements should be set
*/
private void processAttributes(Node node, Element element, boolean elemRefs)
{
NamedNodeMap attributes = element.getAttributes();
for (int i = 0; i < attributes.getLength(); ++i)
{
org.w3c.dom.Node w3cNode = attributes.item(i);
if (w3cNode instanceof Attr)
{
Attr attr = (Attr) w3cNode;
List values;
if (isAttributeSplittingDisabled())
{
values = Collections.singletonList(attr.getValue());
}
else
{
values = PropertyConverter.split(attr.getValue(),
isDelimiterParsingDisabled() ? ATTR_VALUE_DELIMITER
: getListDelimiter());
}
for (Iterator it = values.iterator(); it.hasNext();)
{
Node child = new XMLNode(attr.getName(), elemRefs ? element
: null);
child.setValue(it.next());
node.addAttribute(child);
}
}
}
}
/**
* Deals with elements whose value is a list. In this case multiple child
* elements must be added.
*
* @param parent the parent element
* @param child the child element
* @param trim flag whether texts of elements should be trimmed
*/
private void handleDelimiters(Node parent, Node child, boolean trim)
{
if (child.getValue() != null)
{
List values;
if (isDelimiterParsingDisabled())
{
values = new ArrayList();
values.add(child.getValue().toString());
}
else
{
values = PropertyConverter.split(child.getValue().toString(),
getListDelimiter(), trim);
}
if (values.size() > 1)
{
Iterator it = values.iterator();
// Create new node for the original child's first value
Node c = createNode(child.getName());
c.setValue(it.next());
// Copy original attributes to the new node
for (Iterator itAttrs = child.getAttributes().iterator(); itAttrs
.hasNext();)
{
Node ndAttr = (Node) itAttrs.next();
ndAttr.setReference(null);
c.addAttribute(ndAttr);
}
parent.remove(child);
parent.addChild(c);
// add multiple new children
while (it.hasNext())
{
c = new XMLNode(child.getName(), null);
c.setValue(it.next());
parent.addChild(c);
}
}
else if (values.size() == 1)
{
// we will have to replace the value because it might
// contain escaped delimiters
child.setValue(values.get(0));
}
}
}
/**
* Checks whether the content of the current XML element should be trimmed.
* This method checks whether a <code>xml:space</code> attribute is
* present and evaluates its value. See <a
* href="http://www.w3.org/TR/REC-xml/#sec-white-space">
* http://www.w3.org/TR/REC-xml/#sec-white-space</a> for more details.
*
* @param element the current XML element
* @param currentTrim the current trim flag
* @return a flag whether the content of this element should be trimmed
*/
private boolean shouldTrim(Element element, boolean currentTrim)
{
Attr attr = element.getAttributeNode(ATTR_SPACE);
if (attr == null)
{
return currentTrim;
}
else
{
return !VALUE_PRESERVE.equals(attr.getValue());
}
}
/**
* Creates the <code>DocumentBuilder</code> to be used for loading files.
* This implementation checks whether a specific
* <code>DocumentBuilder</code> has been set. If this is the case, this
* one is used. Otherwise a default builder is created. Depending on the
* value of the validating flag this builder will be a validating or a non
* validating <code>DocumentBuilder</code>.
*
* @return the <code>DocumentBuilder</code> for loading configuration
* files
* @throws ParserConfigurationException if an error occurs
* @since 1.2
*/
protected DocumentBuilder createDocumentBuilder()
throws ParserConfigurationException
{
if (getDocumentBuilder() != null)
{
return getDocumentBuilder();
}
else
{
DocumentBuilderFactory factory = DocumentBuilderFactory
.newInstance();
factory.setValidating(isValidating());
DocumentBuilder result = factory.newDocumentBuilder();
result.setEntityResolver(this);
if (isValidating())
{
// register an error handler which detects validation errors
result.setErrorHandler(new DefaultHandler()
{
public void error(SAXParseException ex) throws SAXException
{
throw ex;
}
});
}
return result;
}
}
/**
* Creates a DOM document from the internal tree of configuration nodes.
*
* @return the new document
* @throws ConfigurationException if an error occurs
*/
protected Document createDocument() throws ConfigurationException
{
try
{
if (document == null)
{
DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
Document newDocument = builder.newDocument();
Element rootElem = newDocument.createElement(getRootElementName());
newDocument.appendChild(rootElem);
document = newDocument;
}
XMLBuilderVisitor builder = new XMLBuilderVisitor(document,
isDelimiterParsingDisabled() ? (char) 0 : getListDelimiter());
builder.processDocument(getRoot());
initRootElementText(document, getRootNode().getValue());
return document;
}
catch (DOMException domEx)
{
throw new ConfigurationException(domEx);
}
catch (ParserConfigurationException pex)
{
throw new ConfigurationException(pex);
}
}
/**
* Sets the text of the root element of a newly created XML Document.
*
* @param doc the document
* @param value the new text to be set
*/
private void initRootElementText(Document doc, Object value)
{
Element elem = doc.getDocumentElement();
NodeList children = elem.getChildNodes();
// Remove all existing text nodes
for (int i = 0; i < children.getLength(); i++)
{
org.w3c.dom.Node nd = children.item(i);
if (nd.getNodeType() == org.w3c.dom.Node.TEXT_NODE)
{
elem.removeChild(nd);
}
}
if (value != null)
{
// Add a new text node
elem.appendChild(doc.createTextNode(String.valueOf(value)));
}
}
/**
* Creates a new node object. This implementation returns an instance of the
* <code>XMLNode</code> class.
*
* @param name the node's name
* @return the new node
*/
protected Node createNode(String name)
{
return new XMLNode(name, null);
}
/**
* Loads the configuration from the given input stream.
*
* @param in the input stream
* @throws ConfigurationException if an error occurs
*/
public void load(InputStream in) throws ConfigurationException
{
load(new InputSource(in));
}
/**
* Load the configuration from the given reader.
* Note that the <code>clear()</code> method is not called, so
* the properties contained in the loaded file will be added to the
* actual set of properties.
*
* @param in An InputStream.
*
* @throws ConfigurationException if an error occurs
*/
public void load(Reader in) throws ConfigurationException
{
load(new InputSource(in));
}
/**
* Loads a configuration file from the specified input source.
* @param source the input source
* @throws ConfigurationException if an error occurs
*/
private void load(InputSource source) throws ConfigurationException
{
try
{
URL sourceURL = getDelegate().getURL();
if (sourceURL != null)
{
source.setSystemId(sourceURL.toString());
}
DocumentBuilder builder = createDocumentBuilder();
Document newDocument = builder.parse(source);
Document oldDocument = document;
document = null;
initProperties(newDocument, oldDocument == null);
document = (oldDocument == null) ? newDocument : oldDocument;
}
catch (Exception e)
{
throw new ConfigurationException("Unable to load the configuration", e);
}
}
/**
* Saves the configuration to the specified writer.
*
* @param writer the writer used to save the configuration
* @throws ConfigurationException if an error occurs
*/
public void save(Writer writer) throws ConfigurationException
{
try
{
Transformer transformer = createTransformer();
Source source = new DOMSource(createDocument());
Result result = new StreamResult(writer);
transformer.transform(source, result);
}
catch (TransformerException e)
{
throw new ConfigurationException("Unable to save the configuration", e);
}
catch (TransformerFactoryConfigurationError e)
{
throw new ConfigurationException("Unable to save the configuration", e);
}
}
/**
* Creates and initializes the transformer used for save operations. This
* base implementation initializes all of the default settings like
* indention mode and the DOCTYPE. Derived classes may overload this method
* if they have specific needs.
*
* @return the transformer to use for a save operation
* @throws TransformerException if an error occurs
* @since 1.3
*/
protected Transformer createTransformer() throws TransformerException
{
Transformer transformer = TransformerFactory.newInstance()
.newTransformer();
transformer.setOutputProperty(OutputKeys.INDENT, "yes");
if (getEncoding() != null)
{
transformer.setOutputProperty(OutputKeys.ENCODING, getEncoding());
}
if (getPublicID() != null)
{
transformer.setOutputProperty(OutputKeys.DOCTYPE_PUBLIC,
getPublicID());
}
if (getSystemID() != null)
{
transformer.setOutputProperty(OutputKeys.DOCTYPE_SYSTEM,
getSystemID());
}
return transformer;
}
/**
* Creates a copy of this object. The new configuration object will contain
* the same properties as the original, but it will lose any connection to a
* source document (if one exists). This is to avoid race conditions if both
* the original and the copy are modified and then saved.
*
* @return the copy
*/
public Object clone()
{
XMLConfiguration copy = (XMLConfiguration) super.clone();
// clear document related properties
copy.document = null;
copy.setDelegate(copy.createDelegate());
// clear all references in the nodes, too
clearReferences(copy.getRootNode());
return copy;
}
/**
* Creates the file configuration delegate for this object. This implementation
* will return an instance of a class derived from <code>FileConfigurationDelegate</code>
* that deals with some specialities of <code>XMLConfiguration</code>.
* @return the delegate for this object
*/
protected FileConfigurationDelegate createDelegate()
{
return new XMLFileConfigurationDelegate();
}
/**
* Adds a collection of nodes directly to this configuration. This
* implementation ensures that the nodes to be added are of the correct node
* type (they have to be converted to <code>XMLNode</code> if necessary).
*
* @param key the key where the nodes are to be added
* @param nodes the collection with the new nodes
* @since 1.5
*/
public void addNodes(String key, Collection nodes)
{
Collection xmlNodes;
if (nodes != null && !nodes.isEmpty())
{
xmlNodes = new ArrayList(nodes.size());
for (Iterator it = nodes.iterator(); it.hasNext();)
{
xmlNodes.add(convertToXMLNode((ConfigurationNode) it.next()));
}
}
else
{
xmlNodes = nodes;
}
super.addNodes(key, xmlNodes);
}
/**
* Converts the specified node into a <code>XMLNode</code> if necessary.
* This is required for nodes that are directly added, e.g. by
* <code>addNodes()</code>. If the passed in node is already an instance
* of <code>XMLNode</code>, it is directly returned, and conversion
* stops. Otherwise a new <code>XMLNode</code> is created, and the
* children are also converted.
*
* @param node the node to be converted
* @return the converted node
*/
private XMLNode convertToXMLNode(ConfigurationNode node)
{
if (node instanceof XMLNode)
{
return (XMLNode) node;
}
XMLNode nd = (XMLNode) createNode(node.getName());
nd.setValue(node.getValue());
nd.setAttribute(node.isAttribute());
for (Iterator it = node.getChildren().iterator(); it.hasNext();)
{
nd.addChild(convertToXMLNode((ConfigurationNode) it.next()));
}
for (Iterator it = node.getAttributes().iterator(); it.hasNext();)
{
nd.addAttribute(convertToXMLNode((ConfigurationNode) it.next()));
}
return nd;
}
/**
* <p>
* Registers the specified DTD URL for the specified public identifier.
* </p>
* <p>
* <code>XMLConfiguration</code> contains an internal
* <code>EntityResolver</code> implementation. This maps
* <code>PUBLICID</code>'s to URLs (from which the resource will be
* loaded). A common use case for this method is to register local URLs
* (possibly computed at runtime by a class loader) for DTDs. This allows
* the performance advantage of using a local version without having to
* ensure every <code>SYSTEM</code> URI on every processed XML document is
* local. This implementation provides only basic functionality. If more
* sophisticated features are required, using
* {@link #setDocumentBuilder(DocumentBuilder)} to set a custom
* <code>DocumentBuilder</code> (which also can be initialized with a
* custom <code>EntityResolver</code>) is recommended.
* </p>
* <p>
* <strong>Note:</strong> This method will have no effect when a custom
* <code>DocumentBuilder</code> has been set. (Setting a custom
* <code>DocumentBuilder</code> overrides the internal implementation.)
* </p>
* <p>
* <strong>Note:</strong> This method must be called before the
* configuration is loaded. So the default constructor of
* <code>XMLConfiguration</code> should be used, the location of the
* configuration file set, <code>registerEntityId()</code> called, and
* finally the <code>load()</code> method can be invoked.
* </p>
*
* @param publicId Public identifier of the DTD to be resolved
* @param entityURL The URL to use for reading this DTD
* @throws IllegalArgumentException if the public ID is undefined
* @since 1.5
*/
public void registerEntityId(String publicId, URL entityURL)
{
if (publicId == null)
{
throw new IllegalArgumentException("Public ID must not be null!");
}
getRegisteredEntities().put(publicId, entityURL);
}
/**
* Resolves the requested external entity. This is the default
* implementation of the <code>EntityResolver</code> interface. It checks
* the passed in public ID against the registered entity IDs and uses a
* local URL if possible.
*
* @param publicId the public identifier of the entity being referenced
* @param systemId the system identifier of the entity being referenced
* @return an input source for the specified entity
* @throws SAXException if a parsing exception occurs
* @since 1.5
*/
public InputSource resolveEntity(String publicId, String systemId)
throws SAXException
{
// Has this system identifier been registered?
URL entityURL = null;
if (publicId != null)
{
entityURL = (URL) getRegisteredEntities().get(publicId);
}
if (entityURL != null)
{
// Obtain an InputSource for this URL. This code is based on the
// createInputSourceFromURL() method of Commons Digester.
try
{
URLConnection connection = entityURL.openConnection();
connection.setUseCaches(false);
InputStream stream = connection.getInputStream();
InputSource source = new InputSource(stream);
source.setSystemId(entityURL.toExternalForm());
return source;
}
catch (IOException e)
{
throw new SAXException(e);
}
}
else
{
// default processing behavior
return null;
}
}
/**
* Returns a map with the entity IDs that have been registered using the
* <code>registerEntityId()</code> method.
*
* @return a map with the registered entity IDs
*/
Map getRegisteredEntities()
{
return registeredEntities;
}
/**
* A specialized <code>Node</code> class that is connected with an XML
* element. Changes on a node are also performed on the associated element.
*/
class XMLNode extends Node
{
/**
* The serial version UID.
*/
private static final long serialVersionUID = -4133988932174596562L;
/**
* Creates a new instance of <code>XMLNode</code> and initializes it
* with a name and the corresponding XML element.
*
* @param name the node's name
* @param elem the XML element
*/
public XMLNode(String name, Element elem)
{
super(name);
setReference(elem);
}
/**
* Sets the value of this node. If this node is associated with an XML
* element, this element will be updated, too.
*
* @param value the node's new value
*/
public void setValue(Object value)
{
super.setValue(value);
if (getReference() != null && document != null)
{
if (isAttribute())
{
updateAttribute();
}
else
{
updateElement(value);
}
}
}
/**
* Updates the associated XML elements when a node is removed.
*/
protected void removeReference()
{
if (getReference() != null)
{
Element element = (Element) getReference();
if (isAttribute())
{
updateAttribute();
}
else
{
org.w3c.dom.Node parentElem = element.getParentNode();
if (parentElem != null)
{
parentElem.removeChild(element);
}
}
}
}
/**
* Updates the node's value if it represents an element node.
*
* @param value the new value
*/
private void updateElement(Object value)
{
Text txtNode = findTextNodeForUpdate();
if (value == null)
{
// remove text
if (txtNode != null)
{
((Element) getReference()).removeChild(txtNode);
}
}
else
{
if (txtNode == null)
{
txtNode = document
.createTextNode(PropertyConverter.escapeDelimiters(
value.toString(), getListDelimiter()));
if (((Element) getReference()).getFirstChild() != null)
{
((Element) getReference()).insertBefore(txtNode,
((Element) getReference()).getFirstChild());
}
else
{
((Element) getReference()).appendChild(txtNode);
}
}
else
{
txtNode.setNodeValue(PropertyConverter.escapeDelimiters(
value.toString(), getListDelimiter()));
}
}
}
/**
* Updates the node's value if it represents an attribute.
*
*/
private void updateAttribute()
{
XMLBuilderVisitor.updateAttribute(getParent(), getName(), getListDelimiter());
}
/**
* Returns the only text node of this element for update. This method is
* called when the element's text changes. Then all text nodes except
* for the first are removed. A reference to the first is returned or
* <b>null </b> if there is no text node at all.
*
* @return the first and only text node
*/
private Text findTextNodeForUpdate()
{
Text result = null;
Element elem = (Element) getReference();
// Find all Text nodes
NodeList children = elem.getChildNodes();
Collection textNodes = new ArrayList();
for (int i = 0; i < children.getLength(); i++)
{
org.w3c.dom.Node nd = children.item(i);
if (nd instanceof Text)
{
if (result == null)
{
result = (Text) nd;
}
else
{
textNodes.add(nd);
}
}
}
// We don't want CDATAs
if (result instanceof CDATASection)
{
textNodes.add(result);
result = null;
}
// Remove all but the first Text node
for (Iterator it = textNodes.iterator(); it.hasNext();)
{
elem.removeChild((org.w3c.dom.Node) it.next());
}
return result;
}
}
/**
* A concrete <code>BuilderVisitor</code> that can construct XML
* documents.
*/
static class XMLBuilderVisitor extends BuilderVisitor
{
/** Stores the document to be constructed. */
private Document document;
/** Stores the list delimiter.*/
private char listDelimiter = AbstractConfiguration.
getDefaultListDelimiter();
/**
* Creates a new instance of <code>XMLBuilderVisitor</code>
*
* @param doc the document to be created
* @param listDelimiter the delimiter for attribute properties with multiple values
*/
public XMLBuilderVisitor(Document doc, char listDelimiter)
{
document = doc;
this.listDelimiter = listDelimiter;
}
/**
* Processes the node hierarchy and adds new nodes to the document.
*
* @param rootNode the root node
*/
public void processDocument(Node rootNode)
{
rootNode.visit(this, null);
}
/**
* Inserts a new node. This implementation ensures that the correct
* XML element is created and inserted between the given siblings.
*
* @param newNode the node to insert
* @param parent the parent node
* @param sibling1 the first sibling
* @param sibling2 the second sibling
* @return the new node
*/
protected Object insert(Node newNode, Node parent, Node sibling1, Node sibling2)
{
if (newNode.isAttribute())
{
updateAttribute(parent, getElement(parent), newNode.getName(), listDelimiter);
return null;
}
else
{
Element elem = document.createElement(newNode.getName());
if (newNode.getValue() != null)
{
String txt = newNode.getValue().toString();
if (listDelimiter != 0)
{
txt = PropertyConverter.escapeDelimiters(txt, listDelimiter);
}
elem.appendChild(document.createTextNode(txt));
}
if (sibling2 == null)
{
getElement(parent).appendChild(elem);
}
else if (sibling1 != null)
{
getElement(parent).insertBefore(elem, getElement(sibling1).getNextSibling());
}
else
{
getElement(parent).insertBefore(elem, getElement(parent).getFirstChild());
}
return elem;
}
}
/**
* Helper method for updating the value of the specified node's
* attribute with the given name.
*
* @param node the affected node
* @param elem the element that is associated with this node
* @param name the name of the affected attribute
* @param listDelimiter the delimiter for attributes with multiple values
*/
private static void updateAttribute(Node node, Element elem, String name, char listDelimiter)
{
if (node != null && elem != null)
{
List attrs = node.getAttributes(name);
StringBuffer buf = new StringBuffer();
char delimiter = (listDelimiter != 0) ? listDelimiter : ATTR_VALUE_DELIMITER;
for (Iterator it = attrs.iterator(); it.hasNext();)
{
Node attr = (Node) it.next();
if (attr.getValue() != null)
{
if (buf.length() > 0)
{
buf.append(delimiter);
}
buf.append(PropertyConverter.escapeDelimiters(attr
.getValue().toString(), delimiter));
}
attr.setReference(elem);
}
if (buf.length() < 1)
{
elem.removeAttribute(name);
}
else
{
elem.setAttribute(name, buf.toString());
}
}
}
/**
* Updates the value of the specified attribute of the given node.
* Because there can be multiple child nodes representing this attribute
* the new value is determined by iterating over all those child nodes.
*
* @param node the affected node
* @param name the name of the attribute
* @param listDelimiter the delimiter for attributes with multiple values
*/
static void updateAttribute(Node node, String name, char listDelimiter)
{
if (node != null)
{
updateAttribute(node, (Element) node.getReference(), name, listDelimiter);
}
}
/**
* Helper method for accessing the element of the specified node.
*
* @param node the node
* @return the element of this node
*/
private Element getElement(Node node)
{
// special treatment for root node of the hierarchy
return (node.getName() != null && node.getReference() != null) ? (Element) node
.getReference()
: document.getDocumentElement();
}
}
/**
* A special implementation of the <code>FileConfiguration</code> interface that is
* used internally to implement the <code>FileConfiguration</code> methods
* for <code>XMLConfiguration</code>, too.
*/
private class XMLFileConfigurationDelegate extends FileConfigurationDelegate
{
public void load(InputStream in) throws ConfigurationException
{
XMLConfiguration.this.load(in);
}
}
}